Description of the Change

This pull requests adds the following to Instant Results:

• Support for the browser history API, so searches can be navigated with the back and forward buttons.
• Shareable/bookmarkable URLs. When the history is updated by searches, the URL is updated with query parameters for the search, and when a page is loaded with these parameters the search modal is opened and pre-populated with results for the search query from the URL.
• Some refactoring to support the above features.

Resolves #2506

Alternate Designs

This PR implements the searchable URLs by defining custom URL parameters only used by Instant Results. These are:

ep-highlight
ep-offset
ep-orderby
ep-order
ep-per_page
ep-post_type
ep-search
ep-relation
ep-max_price
ep-min_price

Taxonomy filters use the argument ep-tax_${taxonomy}, where taxonomy is the taxonomy used for the filter.

This approach means that default WordPress search URLs, like ?s=shirt&post_type=product will not trigger the Instant Results modal to appear. An approach that supports launching Instant Results from default WordPress search URLs, with support for filters from the Facet widget or WooCommerce, might be achievable, but it would require more complicated code to map the default supported parameters to ElasticPress API parameters.

The upside of this approach is that it keeps all the behaviour contained to Instant Results, and keeps the code simpler, but the downside is that any existing shared/bookmarked search URLs will not take advantage of Instant Results, and it means that any shared or bookmarked Instant Results URLs will cease to work if Instant Results is deactivated.

All that being said, the existence of this approach does not necessarily preclude adding support for other parameters in future, possibly as an option.

Possible Drawbacks

There's a few things that are currently limited about the approach:

• So that the history API and shareable URLs work as expected, when closing the modal all URL parameters are cleared. For most WordPress pages 99% of the time this won't be a problem, but if the modal is used on a page that uses a query parameter in its URL, possibly from a plugin, that parameter will be cleared when the modal is closed, which means that refreshing the page after closing the modal may result in something different being loaded. Accommodating this would be a matter of changing the behaviour so that only ElasticPress parameters are removed when closing the modal, but I don't know if that needs to be a blocker for 4.0.
• Not specific accommodations have been made for SEO when it comes to the shareable URLs, so if for any reason an ElasticPress Instant Results URL is indexed or crawled, the content beneath the modal will be seen by the search engine. A workaround for this may be to hide everything except the modal when the modal is opened by URL, so that a search engine indexing an Instant Results URL will only see the search results. Again, doable, but I don't think it's something that necessarily needs to block 4.0.

Verification Process

With the plugin installed and Instant Results activated:

1. Open a page, make note of the original URL.
2. Launch the Instant Results modal by performing a search from the Search block or the theme's search form. The Instant Results modal should open and the URL in the browser's address bar should update with additional parameters for the search query, eg. ?ep-highlight=mark&ep-offset=0&ep-orderby=relevance&ep-order=desc&ep-per_page=6&ep-post_type=&ep-search=block&ep-relation=and.
3. As search parameters are changed, such as filtering, ordering, or the search term, the URL should update to reflect each search.
4. Pressing back and forward in the browser should move backwards and forwards through each change to the search parameters. The search term is debounced so this should not necessarily include every letter change to the search term, unless typing slowly.
5. After opening the modal, pressing Back should close the modal and remove the search parameters from the URL.
6. After performing a search and noting a change in the URL, if the browser is refreshed, or if that full URL is opened in a new tab, then the search modal should automatically open with the same parameters and results as when the URL was originally set.
7. When closing the modal, the URL in the browser's address bar should be updated to remove all search parameters, and pressing Back should re-open the modal and add the search parameters back to the URL.
8. When filtering results, the relevant parameter should update in the URL. If that URL parameter is manually changed in, or added to, a URL, then Instant Results will use that updated value to populate the search parameters and results when it is loaded. However, adding a parameter for a filter should only work if the Facet for that filter has been added in Instant Results settings. For example, it should not be possible to filter results by price using the URL unless the Price range facet has been added. The exception to this is the post type parameter, which is supported regardless of whether the Post type facet is present. This is necessary to support setting the post type from the search form.

Checklist:

• I have read the CONTRIBUTING document.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my change.
• All new and existing tests passed.

Changelog Entry

• Added - Support for shareable URLs to Instant Results.
• Note: After updating from 4.0.0 Beta 1, if filters are not appearing or working as expected, users will need to press Save in ElasticPress > Features > Instant Results to get them working again. If previous Facet selections are missing from the settings field they will need to be reselected manually.

Credits

Props @JakePT